fix(supabase): document the second entry point, and pin the runtime to the engine - #952

Summary

@cipherstash/stack-supabase wraps a Supabase client so that columns you have marked as encrypted are encrypted on the way into the database and decrypted on the way out. It has two entry points: the default one, which uses a native Node module to do the encryption, and @cipherstash/stack-supabase/wasm-inline, which uses a WebAssembly build instead so it can run on edge runtimes — Deno, Supabase Edge Functions, Cloudflare Workers.

Our reference sheet, and the hover documentation that ships to users inside the package's type definitions, both explained why the default entry only runs on Node. The explanation was wrong. They said it was because the wrapper reads your table definitions out of the database at startup ("introspection"), which needs a direct Postgres connection. The real reason is the encryption engine it imports.

That matters because you can turn introspection off. Passing a schemas option makes the wrapper use the table definitions you hand it instead of reading them from the database, and then no Postgres connection is opened at all. Follow the old explanation and you would conclude that doing so lets you deploy the default entry to a Cloudflare Worker. It does not — it fails when the module is imported, before any of your code runs. The fix is to import the wasm-inline entry, which is a different decision entirely.

This started as a docs-only change to the reference sheet and grew: the same wrong explanation turned out to be in three source files whose comments ship to users as .d.ts type definitions, so the PR now carries a patch changeset and two guard tests.

Changes

Reference sheet (docs/reference/supabase-sdk.md)

• The default entry's Node-only restriction is now attributed to the engine it imports, not to introspection, and says explicitly that declaring schemas does not move it.
• "Cannot run in a Worker" now names the edge runtimes. Bare "Worker" is ambiguous and false under one reading — the default entry runs fine inside a Node worker_threads worker.
• Restores the browser prohibition to the default entry. The previous revision of this branch moved it onto the edge entry, which left a reader of the default entry's paragraph with no browser warning at all.
• Drops "they differ only in how the wrapper learns the schema, and therefore in where it can run", which contradicted the entry-point table two lines above it.

Shipped hover documentation (ships as .d.ts, hence the changeset)

• src/create.ts — the comment on the exported factory said "declare your schemas and it runs anywhere". Replaced with "the entry point decides where this runs; schemas decides only whether Postgres is involved."
• src/index.ts and src/create.ts both named @cipherstash/protect-ffi as the native module that loads on import. It is the one package in that graph that deliberately does not load on import; the module-evaluation-time load belongs to @cipherstash/auth. Corrected in both, with the second reason named too: the default entry's bundle carries an import("pg") specifier that a bundler resolves at build time.
• src/wasm-inline.ts — dropped "introspection is half of what made the default entry Node-only".

Guards

• New scripts/__tests__/supabase-runtime-claims.test.mjs: three prose detectors, each unit-tested in both directions, applied to the four files above.
• packages/stack-supabase/__tests__/wasm-entry-edge-safety.test.ts gains three assertions tying the corrected prose to the emitted bundles. Its header comment claimed the stack root pulls both native packages but asserted nothing, so the negative assertions below it could have gone vacuous without failing. That comment repeated the same misattribution and is corrected.

Changeset — @cipherstash/stack-supabase patch. Verified the corrected comments actually reach the published artifact: after a rebuild, dist/index.d.ts:535 carries the new text.

Verification

• pnpm run test:scripts — 854 passed, 50 files. Includes the new guard (37 tests).
• pnpm --filter @cipherstash/stack-supabase test — 568 passed, 16 files.
• The guard was proved fallible rather than assumed to work. Reintroducing "Introspection needs a direct Postgres connection, so this entry cannot run in a Worker" into the reference sheet turns it red on two assertions — the false causal link and the bare "Worker" — and restoring the text returns 37/37.
• The three new bundle assertions were each proved fallible by mutation: dropping the auth import from the stack root, unwrapping the platform requires in protect-ffi/src/load.cts, and reverting index.cts to import * as native each fail a distinct assertion. Tree restored and verified clean afterwards.
• The guard runs in CI. scripts/__tests__/**/*.test.mjs is picked up by pnpm run test:scripts, invoked at .github/workflows/tests.yml:296 in the lint job on every pull request.
• Biome reports 0 errors on every changed file. Caveat, stated rather than omitted: pnpm run code:check repo-wide currently fails on the author's machine for an unrelated reason — ten stale .claude/worktrees/agent-*/biome.json files trigger a "nested root configuration" error. Those are excluded via .git/info/exclude rather than .gitignore, so a fresh CI checkout never sees them. Scoped to the real directories (biome check packages scripts docs e2e examples skills biome-plugins, 861 files) it is 0 errors and 201 pre-existing warnings.

The underlying claims were checked against source, not assumed: packages/protect-ffi/src/index.cts:6-18 (deliberately defers its binary load, guarded by nativeLoading.test.ts), packages/stack/src/index.ts:24 (the static @cipherstash/auth import), and packages/stack-supabase/src/create.ts:303-306 and :364-367 (declaring schemas skips introspection entirely).

Related

Refs #912, #804, #708, #950.

Review notes

Start with docs/reference/supabase-sdk.md and src/create.ts — the latter is the comment users actually see on hover, so it is the highest-leverage correction here.

Deliberately not fixed, to avoid conflicting with open PRs:

• skills/stash-supabase/SKILL.md and packages/stack-supabase/README.md carry the same wrong explanation, and the README ships to customers. docs(supabase): document the wasm-inline entry in the two files that ship #951 is already rewriting those exact README lines, so editing them from two branches would conflict. The README path is recorded in the guard's GUARDED list with a note to add it once docs(supabase): document the wasm-inline entry in the two files that ship #951 lands, so the guard will start enforcing it then.
• The browser-capability claims in examples/supabase-worker and packages/stack/tsup.config.ts belong to docs(stack): stop advertising the WASM entry as browser-capable, and pin the reason against the core #953.

One thing worth raising on #951 rather than here: its rewrite of those README lines keeps the same false "so" and drops the browser half. Cheaper to fix the sentence there before it lands than to let this guard bounce it afterwards.